AmigActive 25/AACD 25.iso/AACD/Sound/MSE/docs/MSE-Compiler.hints

Text File | 1997-05-21 | 12.5 KB | 452 lines

This Hint documentation assumes that you already have read the MSE-Compiler
documentation and that you are familiar with the definition language.

Note that in the following definition examples, not all required parameters
are included.  Only the parameters necessary to clarify are given.
Assumptions are also made that reference definitions have been defined.

See the MSE-Compiler documentation for required parameters and proper
referencing requirements.

----------------------------------------------------------------------------

Shown as:

    $F0, $43, $1n, $34, $01, T2, $00, N2, $00, V2, $F7

    Where:    n  : Device Number
                    T2 : voice channel number
                    V2 : parameter value
                    N2 : parameter number

Discussion:

    T2, V2 and N2 will be set by gadget definitions.  Here, these are
  initialized as 'Byte' (equivalent to 0).

    Normally, the Device Number, or MIDI Channel as it is commonly called,
    will be defined within the 'Define Device' structure.  It could be forced
    here, but it can be changed within MSE so the CHANNEL variable should be
    used.  If you forced it here, changing the MIDI Channel within MSE would
    have no effect.  Remember that CHANNEL is stored in the lower 4 bits, so
    $1n can be intialized as $10.

    Because the MIDI Channel can be changed within MSE, the 'Midi' structure
  is used here to cause the MIDI Channel to be stored in the MIDI message
    each time it is sent out.  It could also be included in gadget
    definitions, but it would have to be defined for every gadget that used
    this message.  Putting it here is more sensible and makes the module
    smaller too.

Defined as:

    Define Midi "M1" (
        Data (
            $F0
            $43
            $10 'Channel $1n
            $34
            $01
            Byte 'T2
            $00
            Byte 'N2
            $00
            Byte 'V2
            $F7
        )
        Midi (
            2 CHANNEL
        )
    )

----------------------------------------------------------------------------

Shown as:

    0    1    2    3    4    5   6    7   8    9   10  : <offset>

    $F0, $43, $1n, $34, $01, T2, $00, N2, $00, V2, $F7

    Where:    V2: -64 to +63 (o/b)

Discussion:

    Usually, when a parameter has a value range with negative numbers, a
  <modifier> definition must be included.  Negative values usually require
    some kind of conversion.  In this case, (o/b) indicates that 'Offset
    Binary' encoding is used.

Defined as:

    Gadget "G1" (
        Type Slider (
            Range -64 63
        )
        Midi "M1" (
            Data (
                9 VALUE Offset 64 Byte 'V2 with Offset Binary encoding
            )
        )
    )

----------------------------------------------------------------------------

Shown as:

    0    1    2    3    4    5   6    7   8    9   10  : <offset>

    $F0, $43, $1n, $34, $01, T2, $00, N2, $00, V2, $F7

    Where:    V2: voice, -31 to +31 (o/b)

Discussion:

    This examples differs from the previous in that the V2 value can also
    have a value for 'voice'.  In this case, 'voice' takes the value of 0,
    -31 = 1, -30 = 2, etc.

    There are a couple ways to define this example.  The first would be
    to use a method similar to the previous, adjusting the Range value (-31
    becomes -32) to account for the additional 'voice' value.

        Gadget "G1" (
            Type Slider (
                Range -32 31
            )
            Midi "M1" (
                Data (
                    9 VALUE Offset 32 Byte 'V2 with Offset Binary encoding
                )
            )
        )

    This would work, but would mean that you had to remember that the value
    of -32 really meant 'voice'.  There is a better way to do this using
    a 'Link' option.  This is a little more work, but is much better.

    A 'Text' link type is used to accommodate the 'voice' option.  This
    forces the remaining values to also be text, so each has to be defined.

    Note that the slider 'Range' is adjusted to start at 0, since this
    is required by links.  This also means that the 'DataValues' option is
    not required within the link definition because the values will already
    be correct.

    Although this method is a bit awkward, keep in mind that links can be
    shared among multiple gadgets.  So, if several parameters use these same
    values, the link need only be defined once.  A new link type may be added
    later to better accommodate this.

Defined as:

    Define Link "L1" (
        Type Texts (
            Data (
                "Voice" "-31" "-30" "-29" "-28" "-27" "-26" "-25" "-24" "-23" "-22"
                "-21" "-20" "-19" "-18" "-17" "-16" "-15" "-14" "-13" "-12" "-11"
                "-10" "-9" "-8" "-7" "-6" "-5" "-4" "-3" "-2" "-1" "0"
                "1" "2" "3" "4" "5" "6" "7" "8" "9" "10" "11" "12" "13" "14" "15"
                "16" "17" "18" "19" "20" "21" "22" "23" "24" "25" "26" "27" "28"
                "29" "30" "31"
            )
        )
    )

    Gadget "G1" (
        Type Slider (
            Range 0 63
            Link "L1"
        )
        Midi "M1" (
            Data (
                9 VALUE Byte 'V2
            )
        )
    )

----------------------------------------------------------------------------

Shown as:

    0    1    2    3    4    5   6    7   8    9   10  : <offset>

    $F0, $43, $1n, $34, $03, T2, $00, N2, $00, V2, $F7

    Where:    V2: -7 to +7 (s/m)

Discussion:

    This is another example of encoding ranges with negative values.  In this
    case, (s/m) indicates that 'Signed Magnitude' encoding is used.

    Note that the maximum value +7 requires 3 bits (0-2), so bit 3 is used to
    hold the magnitude.

Defined as:

    Gadget "G1" (
        Type Slider (
            Range -7 7
        )
        Midi "M1" (
            Data (
                9 VALUE Magnitude 3 Byte 'V2 with Signed Magnitude encoding.
            )
        )
    )

----------------------------------------------------------------------------

Shown as:

    0    1    2    3    4    5   6    7   8   9   10  : <offset>

    $F0, $43, $1n, $34, $04, T2, $00, N2, V1, V2, $F7

    Where:    V1/V2: 0 to 255 (V1;MSB  V2;LS7bits)

Discussion:

    Here, within XBits 'a' represents the MSB (bit 7) and 'b' the lower 7
    bits (0-6).

    Remember that when a value is stored as more than one byte, the <offset>
    value for 'Data' within a 'Midi' definition is the first byte.

Define as:

    Midi "M1" (
        Data (
            8 VALUE XBits abbbbbbb 'V1/V2
        )
    )

----------------------------------------------------------------------------

Shown as:

    0    1    2    3    4    5   6    7   8    9   10  : <offset>

    $F0, $43, $1n, $34, $05, T2, $00, N2, $00, V2, $F7

    Where:    V2: off/on

Discussion:

    Here, 'off' has a value of 0 and 'on' is 1.  A cycle gadget, or a slider
    gadget with a link can be used.  If many parameters use the same values,
    the second method is the better choice.

Define as:

    Gadget "G1" (
        Type Cycle (
            Data (
                "OFF"
                "ON"
            )
        )
        Midi "M1" (
            Data (
                9 VALUE Byte 'V2
            )
        )
    )

    - - OR - -

    Define Link "L1" (
        Type Texts (
            Data (
                "OFF"
                "ON"
            )
        )
    )

    Gadget "G1" (
        Type Slider (
            Range 0 1
            Link "L1"
        )
        Midi "M1" (
            Data (
                9 VALUE Byte 'V2
            )
        )
    )

----------------------------------------------------------------------------

Shown as:

    0    1    2    3    4   5   6    7   8   9   10  : <offset>

    $F0, $43, $1n, $34, T1, T2, $00, N2, V1, V2, $F7

    Where:    V2: b1,0     ;0 to 3    Oscilator output destination
                            b3,2     ;0 to 2    Out_Accumulator input 0 source
                            b4       ;0 to 1    Out_Accumulator input 1 source

Discussion:

    Sometimes, several parameters share the same byte for storing their
    values, each using one or more bits.  In this case, there are 3
    parameters sharing V2: Parameter 1 uses the lower 2 bits (0-1), parameter
    2 uses the next 2 bits (2-3) and parameter 3 uses the next bit (4).

    ************************************************************************
    NOTE: The current method to handle this situation has a problem, related
    to loading patches.  A new feature will be added to MSE in the future
    that will solve this problem.  Until then, there are three possible
    'solutions'.  The first method avoids the problem.  The second, also
    avoids the problem but requires that patch loading not be enabled.  The
    third allows the problem to exist, but requires the user to remember
    certain things about changing some parameters.  Each has it advantages
    and disadvantages.

    1) Only define full patch definitions, ignoring individual parameter
         messages.  This will allow all parameters to update properly when
         loading patches.  The disadvantage of this is that every value change
         will send the full patch message.  With large patch messages this will
         generate a large amount of data transmission.  In most cases, the
         device will be unable to keep up with all the data.  To solve this
         overflow problem, set the 'Updates Final' option in 'Define Device' or
         force manual patch sending by not including the 'Send' option of
         'Midi' and using the menu 'Project/Send' to send the patch any time
         during patch editing.

    2) Only define individual parameter messages, ignoring full patch
         definitions.  This will allow all parameters to update properly, but
         has the disadvantage of not being able to save and/or load patches.

    3) Define both individual parameter and full patch messages, but remember
         that if you adjust one of a group of shared parameters, you must
         re-adjust the others in the group as well.  For example, if three
         shared parameters are defined with both message types and are
         initially set as follows:

                P1 = 10, P2 = 5, P3 = 7

         and then you load a patch with those parameters set as follows:

                P1 = 3, P2 = 1, P3 = 10

         At this point, the patch message is correct, but the individual
         parameter message is wrong.  So far, this is okay because only the
         patch message has been sent.  But, when you manually edit P2 to be set
         at 6.  MSE will send the following incorrect individual parameter
         message values:

                P1 = 10, P2 = 6, P3 = 7

         However, the gadgets will still correctly display as:

                P1 = 3, P2 = 6, P3 = 10

         So, to solve the error, you would then have to remember to manually
         re-set P1 and P3.  After doing so, all three parameters would have been
         updated in the parameter message.  Everything would then work, until
         you loaded another patch.

         Note that, as long as you do not adjust any of the shared parameters,
         loading patches will work fine.
    ************************************************************************

    Regardless of which method you use, the following still applies:

    Parameters that share values require their own 'Define Midi' definition.
    This is so that MSE can send all the shared parameters even when only one
    value is changing.  This means that MSE does not have to remember which
    gadgets represent which bits, nor does it have to determine the other
    parameter values when it sends the message.

    Unlike parameters that do not share, the initial value for these
    parameters must be set within the 'Define Midi' definition.


Define as:

    Define Midi "M1" (
        Data (
            $F0
            $43
            $10 'Channel $1n
            $34
            Byte 'T1
            Byte 'T2
            $00
            Byte 'N2
            Byte 'V1
            %11011 'V2 See defaults below: %1, %10, %11
            $F7
        )
    )

    Gadget "P1" (
        Type Slider (
            Range 0 3
            Default 3 '%11
        )
        Midi "M1" (
            Data (
                9 VALUE Bits 0-1
            )
        )
    )

    Gadget "P2" (
        Type Slider (
            Range 0 2
            Default 2 '%10
        )
        Midi "M1" (
            Data (
                9 VALUE Bits 2-3
            )
        )
    )

    Gadget "P3" (
        Type Slider (
            Range 0 1
            Default 1 '%1
        )
        Midi "M1" (
            Data (
                9 VALUE Bit 4
            )
        )
    )

----------------------------------------------------------------------------


Other Helpful hints:

Some devices do not have textual descriptions of parameters on the display
screens, but do have in the manuals.  Say Device X allows you to
set Parameter #6 to a value of 1, 2 or 3.  Well, that's easy.  Make a
slider gadget with a range of 1 to 3 and text that says "Parameter #6".
Well, that works, but MSE lets you make it even easier to understand.
The manual for Device X says that Parameter #6 is LFO Waveform, and that 1
is SINE, 2 is TRIANGLE and 3 is PULSE... well that makes a lot more sense.
Remember that MSE lets you use any representation of parameter values that
you want.  So, in MSE we could make a cycle gadget with the text "LFO
Waveform" above it with values of "SINE", "TRIANGLE" and "PULSE".  Even
though we see text information in MSE, we can tell it to send #6, 1, 2 and
3 to the device.  Device X will never know what happened, which is good,
because it might get jealous and refuse to operate properly if it did.

Say Device X also has a selection of 150 different waveforms, but it
numbers them from 1 to 150.  It's tough to remember which is which...
wouldn't it be nice if they all had names that meant something to you!
So, go ahead and give them names, call them whatever you want.  MSE can do
that too!  You could do it with a cycle gadget, but a slider gadget with a
Text Type Link would be better.  Try it.

Just because Device X refers to a parameter as ALGSRC0 doesn't mean you
can't call it by something english (or any language for that matter)...
'Oscillator Input 0 Source' makes more sense to us people types.  Doesn't
it?